hhkb
AI

에이전트시스템_01_하네스 엔지니어링

작성자 : Heehyeon Yoo|2026-03-24
# 에이전트시스템# 하네스엔지니어링# 컨텍스트관리# 평가루프# 오케스트레이션

1. 하네스 엔지니어링?

OpenAI가 하네스 엔지니어링을 앞세워 소개한 뒤, 2026년 3월 24일 Anthropic도 비슷한 주제의 글을 냈다. 이쯤 되면 유행어라기보다 실제 문제에 가깝다. 요즘 에이전트 코딩에서 자꾸 걸리는 건 모델의 순간 답변 품질이 아니다. 몇 시간짜리 작업을 맡겼을 때 끝까지 흐름을 잃지 않는가가 더 큰 문제다.

여기서 프롬프트 엔지니어링만으로는 설명이 모자란다. 프롬프트는 한 번의 실행 안에서 모델을 유도하는 방법이다. 하네스는 그 실행 전체를 감싸는 틀에 가깝다. 작업을 어떻게 나눌지, 어떤 도구를 열어 둘지, 실패를 누가 판단할지, 세션이 끊길 때 상태를 어떻게 넘길지를 정하는 쪽이다.

그래서 하네스 엔지니어링은 "더 좋은 결과를 뽑는 법"이 아니다. 에이전트가 긴 작업을 덜 망치게 만드는 방법에 더 가깝다. 같은 모델인데도 결과 차이가 크게 나는 이유도 여기 있다.

2. 긴 작업에서 실제로 생기는 문제

Anthropic이 짚은 첫 번째 문제는 컨텍스트다. 작업이 길어질수록 문맥은 계속 쌓인다. 처음 요구사항, 중간 결정, 실패했던 시도, 아직 안 끝난 작업이 한 덩어리로 뭉친다. 이렇게 되면 모델은 초반의 방향을 덜 또렷하게 붙든다. 아직 끝나지 않았는데도 마무리 쪽으로 서두르는 경우도 생긴다. Anthropic이 말한 context anxiety가 이런 현상이다.

여기서 중요한 구분이 compaction과 reset이다. compaction은 대화를 줄여서 같은 에이전트가 계속 가게 만드는 방식이다. 흐름은 이어진다. 대신 피곤한 상태를 그대로 끌고 간다. reset은 새 컨텍스트에서 다시 시작하는 방식이다. 대신 이전 상태와 다음 단계가 적힌 handoff가 필요하다. 연속성은 조금 줄지만 긴 작업에서는 오히려 이쪽이 더 안정적일 수 있다.

두 번째 문제는 자기평가다. 에이전트는 자기 결과물을 대체로 후하게 본다. 겉보기에 그럴듯하면 실제 결함을 놓치기 쉽다. 기준이 흐릴수록 더 심하다. Anthropic이 evaluator를 따로 둔 이유도 여기 있다. "잘 만들었는가"를 막연히 묻는 대신, 채점 기준을 분리해서 밖으로 꺼내야 한다는 뜻이다.

이건 코딩 작업에도 그대로 들어맞는다. 테스트가 있다고 해서 평가 문제가 끝나는 건 아니다. 테스트는 통과했는데 제품 흐름이 어색하거나, 요구 범위를 빗나가거나, 품질이 낮은 경우가 얼마든지 나온다. 그래서 planner, generator, evaluator 같은 분업이 나온다. 생성자에게 스스로 더 엄격해지라고 요구하는 것보다, 별도 평가자를 두는 편이 보통 더 잘 작동한다.

Anthropic 글이 흥미로운 건 이걸 꽤 구체적으로 보여준다는 점이다. 디자인 작업에서는 generator가 화면을 만들고 evaluator가 Playwright로 직접 페이지를 만지면서 점수를 매긴다. 기준도 막연하지 않다. design quality, originality, craft, functionality처럼 쪼개서 본다. 좋은가 나쁜가를 한 문장으로 끝내지 않고, 어디가 밋밋하고 어디가 어설픈지를 반복적으로 되먹이는 구조다. 한 번 던지고 끝나는 생성보다, 평가를 사이에 두고 여러 번 밀어 붙이는 쪽이 더 나은 결과를 만든다는 얘기다.

긴 코딩 작업에서는 이 구조가 planner까지 포함하는 형태로 넓어진다. planner는 짧은 요구사항을 더 긴 제품 명세로 풀고, generator는 그 명세를 한 번에 다 구현하지 않고 feature 단위로 나눠 간다. evaluator는 마지막에 결과만 보는 역할이 아니다. 각 sprint 전에 이번 턴에서 무엇을 만들고 무엇으로 완료를 판정할지 먼저 generator와 맞춘다. Anthropic이 말한 sprint contract가 이 부분이다. 큰일을 작은 단위로 쪼개고, 평가를 뒤가 아니라 중간에 붙이는 식이다.

3. 좋은 하네스는 무엇을 설계하는가

좋은 하네스는 에이전트의 자유를 늘리는 구조가 아니다. 오히려 몇 가지를 분명하게 고정한다. 일의 단위, 완료 기준, 상태 전달 방식이 대표적이다.

일의 단위가 없으면 에이전트는 큰 작업을 붙잡은 채 계속 헤맨다. 그래서 sprint나 contract 같은 중간 단계가 필요하다. 이번 턴에서 무엇을 만들고, 무엇으로 끝났다고 볼지를 먼저 정해야 한다. 완료 기준이 없으면 결과물은 늘 그럴듯해 보이기만 한다. 그래서 품질 기준을 밖으로 꺼내야 한다. 주관적 작업이면 rubric가 필요하고, 검증 가능한 작업이면 테스트와 threshold가 필요하다. 상태 전달 방식이 없으면 세션이 끊길 때마다 작업이 흔들린다. 그래서 handoff artifact가 중요해진다.

OpenAI가 더 세게 밀어붙인 건 저장소를 에이전트가 읽기 쉬운 형태로 만드는 일이다. 에이전트는 저장소 안에서 찾을 수 없는 정보를 사실상 모른다. 사람 머릿속에만 있는 합의, 채팅에만 남은 맥락, 외부 문서에만 적힌 규칙은 에이전트에게 없는 정보와 비슷하다. 그래서 거대한 AGENTS.md 하나보다 짧은 진입점과 잘 정리된 문서 묶음이 더 낫다.

이 말은 문서화가 중요하다는 수준에서 끝나지 않는다. UI, 로그, 메트릭, 테스트, 계획 문서, 품질 기준까지 에이전트가 직접 읽고 다시 행동으로 연결할 수 있어야 한다는 뜻이다. OpenAI가 agent legibility를 강조한 이유도 그래서다. 에이전트가 볼 수 없는 것은 시스템 안에 있어도 없는 것과 비슷하다.

OpenAI는 이걸 꽤 노골적으로 밀어붙였다. AGENTS.md는 길게 다 설명하는 매뉴얼이 아니라 짧은 입구로 두고, 실제 지식은 docs/ 아래의 구조화된 문서에 넣는다. 실행 계획은 따로 버전 관리하고, 품질 문서와 기술 부채 목록도 저장소 안에 남긴다. 중요한 건 정보가 많으냐가 아니라, 에이전트가 다음에 어디를 읽어야 하는지 자연스럽게 따라갈 수 있느냐다. 큰 파일 하나에 다 넣는 방식은 사람에게도 읽기 힘들지만, 에이전트에게는 더 빨리 썩는다.

여기서 한 걸음 더 가면 저장소만 읽기 쉽게 만드는 것으로도 부족하다. 실행 중인 시스템도 읽을 수 있어야 한다. OpenAI가 UI를 에이전트가 직접 만지게 하고, 로그와 메트릭을 로컬 환경에서 조회하게 하고, 그 결과를 다시 코드 수정으로 연결하게 만든 이유가 그렇다. 에이전트가 코드만 읽고 끝나는 것이 아니라, 실제 동작을 보고 다시 고치는 루프까지 가져야 긴 작업이 버틴다.

문서와 실행 환경을 같이 다뤄야 한다는 점이 하네스 엔지니어링을 더 실무적인 주제로 만든다. 지침만 잘 써서는 안 된다. 에이전트가 어디서 읽고, 무엇을 확인하고, 어떤 신호를 근거로 다음 행동을 정할지까지 같이 설계해야 한다.

결국 하네스 엔지니어링은 모델을 다루는 기술이면서 동시에 환경을 다루는 기술이다. 프롬프트만 잘 쓴다고 긴 작업이 안정적으로 굴러가지는 않는다. 작업 단위를 어떻게 자를지, 평가를 어디에 둘지, 컨텍스트를 어떻게 넘길지, 저장소를 얼마나 읽기 쉽게 만들지를 같이 설계해야 한다. 요즘 이 주제가 커진 이유도 여기 있다. 이제 성능은 모델 내부만이 아니라, 그 모델이 일하는 바깥 구조에서도 결정된다.

4. 하네스는 공짜가 아니다

여기서 한 가지 더 봐야 할 건 비용이다. 좋은 하네스는 성능을 올려 주지만, 대가 없이 생기지 않는다. reset은 문맥 피로를 줄여 주는 대신 orchestration이 복잡해지고 토큰 비용과 지연이 늘어난다. evaluator를 붙이면 품질은 올라가지만 반복 횟수와 실행 시간이 함께 늘어난다. planner를 두면 방향은 또렷해지지만, 잘못 만든 계획이 아래 단계로 번질 위험도 생긴다.

그래서 하네스 엔지니어링은 "에이전트를 많이 붙이면 된다"는 이야기가 아니다. 어디서 분리할지, 어디는 한 세션으로 두고 어디서 끊을지, 어떤 평가는 자동화하고 어떤 평가는 사람에게 남길지를 고르는 일이다. 구조를 많이 세운다고 무조건 좋아지는 게 아니라, 작업의 성격에 맞게 실패 지점을 줄이는 쪽이 중요하다.

결국 하네스의 품질은 에이전트를 얼마나 화려하게 배치했는지보다, 어떤 실패를 실제로 줄였는지로 봐야 한다. 그 점에서 하네스 엔지니어링은 프롬프트 기법 모음이 아니라, 장시간 자율 작업을 굴리기 위한 운영 설계에 더 가깝다.

참고 자료